Repository navigation
docs: cover CLI tokens, WES and TRS - #136
Merged
Merged
Conversation
Update the CLI user guide to ga4gh/ga4gh-sdk main at af0e021: the CLI now sends tokens (oauth_access_token_env with an LS Login access token), has WES and TRS commands and configuration profiles. The page explains how to get a token and pass it in a variable, sends TES tasks through proTES, runs and follows WES runs, finds and downloads workflows from WorkflowHub, and lists what is still planned (device-flow login, binaries, container image, TES log downloads). The researchers index and the demos table no longer say that the CLI can't send tokens or run workflows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
Reviewer's GuideDocumentationUpdate the CLI guide and its researcher-facing index entries to document token configuration, profiles, TES tasks, WES runs, and TRS workflow discovery against the current SDK.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Documentation build overview
9 files changed ·
|
# Conflicts: # docs/researchers/index.md
uniqueg
marked this pull request as ready for review
November 13, 2026 16:31
Contributor
Linked issuesChecked at commit be4934e #124 docs: CLI login and workflow runs · 1 of 2 met · 1 to check by hand
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 3 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="docs/researchers/cli.md" line_range="191" />
<code_context>
+ The section can also hold the token itself (`oauth_access_token`), but
+ then the file keeps it on disk. Use `oauth_access_token_env` instead.
+ Send tokens only over `https`: if `base_path` of a remote service starts
+ with `http:`, the CLI warns, but still sends the token.
+
+If the variable isn't set, the CLI stops before it sends a request, for
</code_context>
<issue_to_address>
**HTTP requests leak access tokens**
When a user configures a remote TES or WES service with an `http:` base path, `ga4gh-cli` warns but still attaches the LS Login bearer token to requests, so anyone able to observe the network traffic can capture and reuse the credential.
Make the CLI refuse to send credentials to remote services over plaintext HTTP.
</issue_to_address>
### Comment 2
<location path="docs/researchers/cli.md" line_range="176" />
<code_context>
+
+ ```bash
+ read -rs LS_LOGIN_TOKEN # paste the token, then press Enter
+ export LS_LOGIN_TOKEN
+ ```
+
</code_context>
<issue_to_address>
**Tokens persist in child processes**
When a user launches an untrusted program from the same terminal after using the CLI, `export LS_LOGIN_TOKEN` leaves the access token in the shell environment after CLI use, so any subsequently launched untrusted program in that terminal can inherit and read the credential.
Show how to scope the variable to CLI invocations or unset it when CLI use is finished.
</issue_to_address>
### Comment 3
<location path="docs/researchers/cli.md" line_range="384" />
<code_context>
--n "<name of the task>"` whether it exists, so that it doesn't run twice.
+the task runs anyway. The CLI sends a task only once, and its error says so
+when the task may have been accepted. Before you send it again, check with
+`ga4gh-cli tes list -n "<name of the task>"` whether it exists, so that it
+doesn't run twice.
</code_context>
<issue_to_address>
**Duplicate tasks or workflows execute**
When an accepted submission is not yet visible in `tes list` or `wes list`, or another caller retries before it appears, `tes list` or `wes list` returns no match, so the retry guidance leads callers to submit again and the service queues duplicate tasks or workflows.
Revise the retry guidance to explain that a missing listing entry does not establish that a submission was rejected and that resubmitting can create a duplicate.
Also at `docs/researchers/cli.md:434`.
</issue_to_address>Sourcery assessment
Approval pending. 3 findings to address first.
Blocking findings: docs/researchers/cli.md:191, docs/researchers/cli.md:176, docs/researchers/cli.md:384
Per the maintainer's decision, #124 documents only the token in a variable named by oauth_access_token_env; a CLI login command is not needed. Remove the "no login command" warning and the device-flow row of "What's coming". Also address review findings: show how to unset the token variable when done, say never to name it in sections with http: base paths, and explain that a task or run missing from the list right after an error doesn't prove it was rejected. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updates the researcher page "Use the Command Line" (
docs/researchers/cli.md) to ga4gh/ga4gh-sdkmainat commitaf0e021. Since the last version of the page (8b8030f), the CLI sends tokens, has WES and TRS commands, and supports configuration profiles. The page now covers the steps that #124 and #110 ask for:read -rs LS_LOGIN_TOKEN), and name the variable withoauth_access_token_envin theTES/WESsections. Tokens in the file itself are discouraged; thehttp:warning and the error for an unset variable are documented.TESsection points at proTES;tes create/list/get/status/cancelas before, with the checks oftes createand the new error output (HTTP status only, no service answer).wes run(all options, attachments) andwes list/status/get/cancel.trscommands against WorkflowHub, including--plainand--zip.default_profile,--profile,GA4GH_CLI_PROFILE.No
mkdocs.ymlchange: the page is already in the nav.Closes #124
Light lane: docs only. I reviewed the diff myself against
cli/src, the--helpoutput anddocs/authentication.mdof the SDK; every command and option shown exists ataf0e021.Verification
python scripts/check_names.py: passedmkdocs build --strict: passed, no warningspytest: 25 passed, 100% coverageBuilt
ga4gh-cliataf0e021inrust:1.97(cargo build -p ga4gh-cli --locked) and compared all--helpoutputs with the pageCloud Registry of ELIXIR On-Cloud, anonymously:
registry list,list --type tes,get GC6ZQG,types; output as shownWorkflowHub, anonymously:
trs tools,tool 3,versions 3,version 3 1,files 3 1 --type CWL(also--zip),descriptor ... --plain,testsLocal mock TES/WES at
/ga4gh/tes/v1and/ga4gh/wes/v1, with a dummy token inLS_LOGIN_TOKENand a profiles file: alltesandwescommands on the page hit the right paths and every request, includingservice-info, carried the bearer token;--profilebefore and after the command andGA4GH_CLI_PROFILEboth worked; unset variable stops before any request; wrong token gives401 Unauthorized; absolute attachment paths are rejectedCI: all checks passed (PR title, Docs, Test, CI passed, CodeQL, Read the Docs preview)
CI after merging
main(Krini guide, data centre tutorial; conflict in the researchers index resolved by keeping both rows): all checks passed againMerged
mainlocally first:check_names.py,mkdocs build --strictandpytestpassed againReview fixes (Sourcery threads): the page shows
unset LS_LOGIN_TOKENand says that programs started from the terminal can read the variable; it says never to name the token variable in a section with anhttp:base path (exceptlocalhost); and it says that a task or run missing from the list right after an error doesn't prove it was rejected. The CLI itself still sends tokens overhttp:with a warning; that is CLI behaviour in ga4gh/ga4gh-sdk, outside this repo. After these changes:check_names.py,mkdocs build --strictandpytest(25 passed, 100% coverage) passed locally.Not checked live
tesandwessteps were not run with a real LS Login token against a deployed proTES or WES of ELIXIR On-Cloud: none is published for researchers yet (the Cloud Registry lists only the BIH Funnel TES and the registry). They were checked against the mock above; the page says so in "How this page was tested".oauth_access_token_env. Per the maintainer's decision (2026-11-13), docs: CLI login and workflow runs #124 documents only this; a device-flow login command (feat(cli): log in with the OIDC device flow ga4gh/ga4gh-sdk#90) is not needed and is not part of this PR, so the page no longer mentions it.The anchors that docs PR #139 links to (
#install,#configure,#log-in-with-ls-login,#find-services-in-the-cloud-registry,#create-a-task,#get-a-task,#get-the-state-of-a-task,#check-for-errors,#start-a-run,#follow-a-run) all exist on the page.🤖 Generated with Claude Code